/**
 * Software License, Version 1.0
 * 
 * Copyright 2003 The Trustees of Indiana University.  All rights reserved.
 * 
 *
 *Redistribution and use in source and binary forms, with or without 
 *modification, are permitted provided that the following conditions are met:
 *
 *1) All redistributions of source code must retain the above copyright notice,
 * the list of authors in the original source code, this list of conditions and
 * the disclaimer listed in this license;
 *2) All redistributions in binary form must reproduce the above copyright 
 * notice, this list of conditions and the disclaimer listed in this license in
 * the documentation and/or other materials provided with the distribution;
 *3) Any documentation included with all redistributions must include the 
 * following acknowledgement:
 *
 *"This product includes software developed by the Community Grids Lab. For 
 * further information contact the Community Grids Lab at 
 * http://communitygrids.iu.edu/."
 *
 * Alternatively, this acknowledgement may appear in the software itself, and 
 * wherever such third-party acknowledgments normally appear.
 * 
 *4) The name Indiana University or Community Grids Lab or NaradaBrokering, 
 * shall not be used to endorse or promote products derived from this software 
 * without prior written permission from Indiana University.  For written 
 * permission, please contact the Advanced Research and Technology Institute 
 * ("ARTI") at 351 West 10th Street, Indianapolis, Indiana 46202.
 *5) Products derived from this software may not be called NaradaBrokering, 
 * nor may Indiana University or Community Grids Lab or NaradaBrokering appear
 * in their name, without prior written permission of ARTI.
 * 
 *
 * Indiana University provides no reassurances that the source code provided 
 * does not infringe the patent or any other intellectual property rights of 
 * any other entity.  Indiana University disclaims any liability to any 
 * recipient for claims brought by any other entity based on infringement of 
 * intellectual property rights or otherwise.  
 *
 *LICENSEE UNDERSTANDS THAT SOFTWARE IS PROVIDED "AS IS" FOR WHICH NO 
 *WARRANTIES AS TO CAPABILITIES OR ACCURACY ARE MADE. INDIANA UNIVERSITY GIVES
 *NO WARRANTIES AND MAKES NO REPRESENTATION THAT SOFTWARE IS FREE OF 
 *INFRINGEMENT OF THIRD PARTY PATENT, COPYRIGHT, OR OTHER PROPRIETARY RIGHTS. 
 *INDIANA UNIVERSITY MAKES NO WARRANTIES THAT SOFTWARE IS FREE FROM "BUGS", 
 *"VIRUSES", "TROJAN HORSES", "TRAP DOORS", "WORMS", OR OTHER HARMFUL CODE.  
 *LICENSEE ASSUMES THE ENTIRE RISK AS TO THE PERFORMANCE OF SOFTWARE AND/OR 
 *ASSOCIATED MATERIALS, AND TO THE PERFORMANCE AND VALIDITY OF INFORMATION 
 *GENERATED USING SOFTWARE.
 */
package cgl.narada.wsinfra.deployment;
import javax.xml.soap.SOAPMessage;

import cgl.narada.wsinfra.exception.DeploymentException;
import cgl.narada.wsinfra.exception.MessageFlowException;
import cgl.narada.wsinfra.exception.ProcessingException;

/** This interface outlines functionality within the FilterPipeline. 
    Specifically, filters can be dynamically added, removed, substituted and 
    reorganized within the filter pipeline. Furthermore, individual filters
    can configure themselves to be part of the input OR the output flow within
    the FilterPipeline.

    @author Shrideep Pallickara
    $Date: 2005/07/29 22:41:29 $
    $Revision: 1.8 $
*/

public interface FilterPipeline {

  /** Register the service message listener for this filter pipeline. */
  public void 
  registerServiceMessageListener(ServiceMessageListener serviceMessageListener)
    throws DeploymentException;
  

  /** Register a networking substrate for this filter pipeline. */
  public void registerNetworkSubstrate(NetworkSubstrate networkSubstrate)
    throws DeploymentException;
  
  
  /** Checks to see if a given filter is part of this pipeline. */
  public boolean isPartOfPipeline(Filter filter);

  /** Add a filter to this filter pipeline. */
  public void addFilter(Filter filter) throws DeploymentException;

  /** Add a filter to this filter pipeline at a specific position. */
  public void addFilterAt(Filter filter, int position)
    throws DeploymentException;


  /** Remove a filter from this filter-pipeline. */
  public void removeFilter(Filter filter) throws DeploymentException;
  
  /** Remove a filter at the specified location. */
  public void removeFilterAt(int position) throws DeploymentException;

  /** This method moves a filter within a filter chain to the specified 
      position. The positions of all the other filters within the filter 
      pipeline are adjusted accordingly. For e.g.
      F1 --- F2 --- F3 --- F4 --- F5, if you move F3 to the 5th position
      the filter chain would now look like F1 --- F2 --- F4 --- F5 --- F3. 
      This method throws an exception if the filter does not belong to this
      filter pipeline OR if the position is not a valid one. The position
      number CANNOT exceed the number of filters within the filter chain. 
      Also, filter numbering begins at 0. */
  public void moveFilter(Filter filter, int position) 
    throws DeploymentException;


  /** This method replaces the existing filter at a given position with
      the specified one. */
  public void replaceFilter(Filter filter, int position) 
    throws DeploymentException;
  
  
   /** This method executes ALL the filters within the input part of the
      filter pipeline. This method is typically used for SOAP messages that
      are received over the network. */
  public void executeInputFilters(SOAPContext soapContext);

  /** Executes ALL the output filters within the Filter pipeline. This method 
      is typically called for SOAP messages received from the application.*/
  public void executeOutputFilters(SOAPContext soapContext) 
    throws DeploymentException, MessageFlowException, ProcessingException;


  /** Process a message received over the network. */
  public void processMessageFromNetwork(SOAPMessage soapMessage);
  
  /** Process a message received from the application. */
  public void processMessageFromApplication(SOAPMessage soapMessage)
    throws DeploymentException, MessageFlowException, ProcessingException;



  /** Injects a message based on the filter's position within the filter 
      pipeline towards the application. */
  public void injectMessageTowardsApplication(SOAPMessage soapMessage, 
					      Filter filter) 
    throws DeploymentException;


  
  /** Injects a message at a specific location within the filter pipeline 
      towards the application. */
  public void 
  injectMessageTowardsApplication(SOAPMessage soapMessage, int position) 
    throws DeploymentException;


  /** Injects a message at the filter immediately following this filter in
      the path TOWARDS the NETWORK. */
  public void 
  injectMessageTowardsNetwork(SOAPMessage soapMessage, Filter filter) 
    throws DeploymentException, MessageFlowException, ProcessingException;


  /** Injects a message at a specific location within the filter pipeline. */
  public void 
  injectMessageTowardsNetwork(SOAPMessage soapMessage, int position) 
    throws DeploymentException, MessageFlowException, ProcessingException;


  /** Retrieves the position of the filter within the filter pipeline,
      irrespective of whether it is an input filter or output filter or
      both. */
  public int getPositionInFilterPipeline(Filter filter) 
    throws DeploymentException;



  /** Gets the position of a given filter within the FilterPipeline. The
      second variable returns <i>position</i> depending on whether it is
      within the input path or the output path. Specifically, this method
      determines how many input/output filters reside before the filter in 
      question.*/
  public int getPositionInFilterPipeline(Filter filter, boolean input)
    throws DeploymentException ;

  /** Gets the num of filters that comprise the filter pipeline. */
  public int getTotalNumberOfFilters();
  

  /** Gets the total number of input filters. */
  public int getNumberOfInputFilters();
  
  /** Gets the total number of output filters. */
  public int getNumberOfOutputFilters();
  
  
  /** Retrive an enumeration of the filters that are part of the filter
      pipeline. */
  public Filter[] getFilters();


  /** Set the identifier of the filter pipeline.*/
  public void setIdentifier(String identifier)
    throws DeploymentException;

  /** Retrieve the identifier of the filter pipeline. */
  public String getIdentifier();
  
}





